package com.cencat.route.service;

import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.cencat.route.entity.Dispatch;
import com.cencat.route.vo.DispatchVO;
import com.cencat.route.dto.DispatchDTO;
import com.cencat.route.dto.DispatchQueryDTO;
import com.cencat.route.dto.DispatchBatchUpdateDTO;
import com.cencat.route.dto.DispatchStatisticsDTO;
import com.cencat.route.dto.DispatchMatchDTO;
import jakarta.validation.constraints.NotNull;
import java.time.LocalDateTime;
import java.util.List;
import java.util.Map;

/**
 * 调度管理服务接口
 * 提供调度的增删改查、统计分析、智能匹配等业务功能
 * 
 * @author cencat
 * @version 1.0
 * @since 2025-01-20
 */
public interface DispatchService {

    /**
     * 分页查询调度列表
     * 
     * @param page 分页参数
     * @param queryDTO 查询条件
     * @return 分页结果
     */
    Page<DispatchVO> getDispatchList(Page<Dispatch> page, DispatchQueryDTO queryDTO);

    /**
     * 根据ID获取调度详情
     * 
     * @param id 调度ID
     * @return 调度详情
     */
    DispatchVO getDispatchById(@NotNull Long id);

    /**
     * 创建新调度
     * 
     * @param dispatchDTO 调度信息
     * @return 创建结果
     */
    Boolean createDispatch(@NotNull DispatchDTO dispatchDTO);

    /**
     * 更新调度信息
     * 
     * @param id 调度ID
     * @param dispatchDTO 调度信息
     * @return 更新结果
     */
    Boolean updateDispatch(@NotNull Long id, @NotNull DispatchDTO dispatchDTO);

    /**
     * 删除调度
     * 
     * @param id 调度ID
     * @return 删除结果
     */
    Boolean deleteDispatch(@NotNull Long id);

    /**
     * 批量删除调度
     * 
     * @param ids 调度ID列表
     * @return 删除结果
     */
    Boolean batchDeleteDispatches(@NotNull List<Long> ids);

    /**
     * 批量更新调度状态
     * 
     * @param batchUpdateDTO 批量更新参数
     * @return 更新结果
     */
    Boolean batchUpdateDispatchStatus(@NotNull DispatchBatchUpdateDTO batchUpdateDTO);

    /**
     * 批量更新调度优先级
     * 
     * @param ids 调度ID列表
     * @param priority 优先级
     * @return 更新结果
     */
    Boolean batchUpdatePriority(@NotNull List<Long> ids, @NotNull Integer priority);

    /**
     * 批量分配司机
     * 
     * @param ids 调度ID列表
     * @param driverId 司机ID
     * @return 分配结果
     */
    Boolean batchAssignDriver(@NotNull List<Long> ids, @NotNull Long driverId);

    /**
     * 批量分配车辆
     * 
     * @param ids 调度ID列表
     * @param vehicleId 车辆ID
     * @return 分配结果
     */
    Boolean batchAssignVehicle(@NotNull List<Long> ids, @NotNull Long vehicleId);

    /**
     * 获取调度统计信息
     * 
     * @param statisticsDTO 统计参数
     * @return 统计结果
     */
    Map<String, Object> getDispatchStatistics(@NotNull DispatchStatisticsDTO statisticsDTO);

    /**
     * 智能匹配调度
     * 
     * @param matchDTO 匹配参数
     * @return 匹配结果
     */
    List<DispatchVO> intelligentMatchDispatches(@NotNull DispatchMatchDTO matchDTO);

    /**
     * 获取紧急调度
     * 
     * @param limit 数量限制
     * @return 紧急调度列表
     */
    List<DispatchVO> getUrgentDispatches(@NotNull Integer limit);

    /**
     * 获取待处理调度
     * 
     * @param limit 数量限制
     * @return 待处理调度列表
     */
    List<DispatchVO> getPendingDispatches(@NotNull Integer limit);

    /**
     * 获取进行中调度
     * 
     * @param limit 数量限制
     * @return 进行中调度列表
     */
    List<DispatchVO> getInProgressDispatches(@NotNull Integer limit);

    /**
     * 获取已完成调度
     * 
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @param limit 数量限制
     * @return 已完成调度列表
     */
    List<DispatchVO> getCompletedDispatches(@NotNull LocalDateTime startTime, @NotNull LocalDateTime endTime, 
                                            @NotNull Integer limit);

    /**
     * 获取超时调度
     * 
     * @param limit 数量限制
     * @return 超时调度列表
     */
    List<DispatchVO> getOverdueDispatches(@NotNull Integer limit);

    /**
     * 获取司机调度列表
     * 
     * @param driverId 司机ID
     * @param status 状态
     * @param limit 数量限制
     * @return 司机调度列表
     */
    List<DispatchVO> getDriverDispatches(@NotNull Long driverId, String status, @NotNull Integer limit);

    /**
     * 获取车辆调度列表
     * 
     * @param vehicleId 车辆ID
     * @param status 状态
     * @param limit 数量限制
     * @return 车辆调度列表
     */
    List<DispatchVO> getVehicleDispatches(@NotNull Long vehicleId, String status, @NotNull Integer limit);

    /**
     * 获取路线调度列表
     * 
     * @param routeId 路线ID
     * @param status 状态
     * @param limit 数量限制
     * @return 路线调度列表
     */
    List<DispatchVO> getRouteDispatches(@NotNull Long routeId, String status, @NotNull Integer limit);

    /**
     * 检查调度是否存在
     * 
     * @param id 调度ID
     * @return 是否存在
     */
    Boolean existsById(@NotNull Long id);

    /**
     * 检查调度编号是否存在
     * 
     * @param dispatchNo 调度编号
     * @param excludeId 排除的调度ID
     * @return 是否存在
     */
    Boolean existsByDispatchNo(@NotNull String dispatchNo, Long excludeId);

    /**
     * 分配调度
     * 
     * @param dispatchId 调度ID
     * @param driverId 司机ID
     * @param vehicleId 车辆ID
     * @return 分配结果
     */
    Boolean assignDispatch(@NotNull Long dispatchId, @NotNull Long driverId, @NotNull Long vehicleId);

    /**
     * 开始调度
     * 
     * @param dispatchId 调度ID
     * @return 开始结果
     */
    Boolean startDispatch(@NotNull Long dispatchId);

    /**
     * 完成调度
     * 
     * @param dispatchId 调度ID
     * @return 完成结果
     */
    Boolean completeDispatch(@NotNull Long dispatchId);

    /**
     * 取消调度
     * 
     * @param dispatchId 调度ID
     * @param reason 取消原因
     * @return 取消结果
     */
    Boolean cancelDispatch(@NotNull Long dispatchId, @NotNull String reason);

    /**
     * 暂停调度
     * 
     * @param dispatchId 调度ID
     * @param reason 暂停原因
     * @return 暂停结果
     */
    Boolean pauseDispatch(@NotNull Long dispatchId, @NotNull String reason);

    /**
     * 恢复调度
     * 
     * @param dispatchId 调度ID
     * @return 恢复结果
     */
    Boolean resumeDispatch(@NotNull Long dispatchId);

    /**
     * 重新分配调度
     * 
     * @param dispatchId 调度ID
     * @param newDriverId 新司机ID
     * @param newVehicleId 新车辆ID
     * @param reason 重新分配原因
     * @return 重新分配结果
     */
    Boolean reassignDispatch(@NotNull Long dispatchId, @NotNull Long newDriverId, 
                             @NotNull Long newVehicleId, @NotNull String reason);

    /**
     * 获取调度进度
     * 
     * @param dispatchId 调度ID
     * @return 进度信息
     */
    Map<String, Object> getDispatchProgress(@NotNull Long dispatchId);

    /**
     * 更新调度进度
     * 
     * @param dispatchId 调度ID
     * @param progress 进度百分比
     * @param currentLocation 当前位置
     * @return 更新结果
     */
    Boolean updateDispatchProgress(@NotNull Long dispatchId, @NotNull Integer progress, 
                                   @NotNull String currentLocation);

    /**
     * 导出调度数据
     * 
     * @param queryDTO 查询条件
     * @return 导出数据
     */
    List<DispatchVO> exportDispatches(@NotNull DispatchQueryDTO queryDTO);

    /**
     * 导入调度数据
     * 
     * @param dispatches 调度数据列表
     * @return 导入结果
     */
    Boolean importDispatches(@NotNull List<DispatchDTO> dispatches);

    /**
     * 自动调度分配
     * 
     * @param routeId 路线ID
     * @param requirements 需求条件
     * @return 自动分配结果
     */
    Boolean autoAssignDispatch(@NotNull Long routeId, @NotNull String requirements);

    /**
     * 优化调度路径
     * 
     * @param dispatchId 调度ID
     * @return 优化结果
     */
    Boolean optimizeDispatchRoute(@NotNull Long dispatchId);
}